Skip to main content

Troubleshooting 502 Errors: YAML Syntax & Broken Links

This guide covers a specific case where a 502 Bad Gateway error was caused by a build failure due to invalid YAML frontmatter syntax and broken internal links after a file extension conversion.

1. YAML Syntax Error (Build Failure)​

The Problem​

When you run docker restart docusaurus, the container fails to build the site because of a syntax error in your markdown's frontmatter. This results in the container stuck in a "restarting" loop, leading to a persistent 502 Bad Gateway error.

How to Diagnose​

Check the container logs for YAMLException:

sudo docker logs docusaurus | grep -A 5 "YAMLException"

Common Error Message: YAMLException: incomplete explicit mapping pair; a key node is missed; or followed by a non-tabulated empty line

The Cause​

Docusaurus uses YAML for the frontmatter block (between the --- lines). Colons (:) are special characters in YAML. If your title or sidebar_label contains a colon, it must be enclosed in quotes.

Incorrect:

title: My Guide: How to Install

Correct:

title: "My Guide: How to Install"

The Solution​

  1. Identify the failing file from the logs.
  2. Edit the file and wrap the offending string in double quotes.
  3. Restart the container: sudo docker restart docusaurus.

The Problem​

After converting all files from .md to .mdx, clicking on internal links resulting in 404 errors, or the build process showing multiple [WARNING] Broken link messages.

The Cause​

Markdown files typically link to each other using relative paths like [See Guide](./other-guide.md). When you rename the file to .mdx, the link must also be updated to end in .mdx.

The Solution (Bulk Update)​

If you have many files, you can use a command to replace all .md) occurrences with .mdx) across your entire documentation folder:

find /path/to/docs -name "*.mdx" -exec sed -i 's/\.md)/.mdx)/g' {} +

Verification​

Always verify the build by following the logs:

sudo docker logs -f docusaurus

Look for [SUCCESS] Generated static files in "build" and ensure no "Broken link" warnings remain.

Summary Checklist​

  • Check logs for YAMLException.
  • Wrap titles with colons in double quotes: "Title: Subtitle".
  • Ensure all relative links end with .mdx if the target file was converted.
  • Restart the container and wait for the "Serving" success message.